home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kconfigskeleton.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  36.5 KB  |  1,231 lines

  1. /*
  2.  * This file is part of KDE.
  3.  * 
  4.  * Copyright (c) 2001,2002,2003 Cornelius Schumacher <schumacher@kde.org>
  5.  * Copyright (c) 2003 Waldo Bastian <bastian@kde.org>
  6.  * 
  7.  * This library is free software; you can redistribute it and/or
  8.  * modify it under the terms of the GNU Library General Public
  9.  * License as published by the Free Software Foundation; either
  10.  * version 2 of the License, or (at your option) any later version.
  11.  * 
  12.  * This library is distributed in the hope that it will be useful,
  13.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.  * Library General Public License for more details.
  16.  * 
  17.  * You should have received a copy of the GNU Library General Public License
  18.  * along with this library; see the file COPYING.LIB.  If not, write to
  19.  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20.  * Boston, MA 02110-1301, USA.
  21.  */
  22.  
  23. #ifndef _KCONFIGSKELETON_H
  24. #define _KCONFIGSKELETON_H
  25.  
  26. #include <qcolor.h>
  27. #include <qdatetime.h>
  28. #include <qfont.h>
  29. #include <qpoint.h>
  30. #include <qptrlist.h>
  31. #include <qdict.h>
  32. #include <qrect.h>
  33. #include <qsize.h>
  34. #include <qstringlist.h>
  35. #include <qvariant.h>
  36. #include <kconfig.h>
  37. #include <kglobalsettings.h>
  38.  
  39.   /**
  40.    * @short Class for storing a preferences setting
  41.    * @author Cornelius Schumacher
  42.    * @see KConfigSkeleton
  43.    * 
  44.    * This class represents one preferences setting as used by @ref KConfigSkeleton.
  45.    * Subclasses of KConfigSkeletonItem implement storage functions for a certain type of
  46.    * setting. Normally you don't have to use this class directly. Use the special
  47.    * addItem() functions of KConfigSkeleton instead. If you subclass this class you will
  48.    * have to register instances with the function KConfigSkeleton::addItem().
  49.    */
  50.   class KDECORE_EXPORT KConfigSkeletonItem
  51.   {
  52.   public:
  53.     typedef QValueList < KConfigSkeletonItem * >List;
  54.     typedef QDict < KConfigSkeletonItem > Dict;
  55.     typedef QDictIterator < KConfigSkeletonItem > DictIterator;
  56.  
  57.     /**
  58.      * Constructor.
  59.      * 
  60.      * @param group Config file group.
  61.      * @param key Config file key.
  62.      */
  63.     KConfigSkeletonItem(const QString & group, const QString & key)
  64.       :mGroup(group),mKey(key), mIsImmutable(true)
  65.     {
  66.     }
  67.  
  68.     /**
  69.      * Destructor.
  70.      */
  71.     virtual ~KConfigSkeletonItem()
  72.     {
  73.     }
  74.  
  75.     /**
  76.      * Set config file group.
  77.      */
  78.     void setGroup( const QString &group )
  79.     {
  80.       mGroup = group;
  81.     }
  82.  
  83.     /**
  84.      * Return config file group.
  85.      */
  86.     QString group() const
  87.     {
  88.       return mGroup;
  89.     }
  90.  
  91.     /**
  92.      * Set config file key.
  93.      */
  94.     void setKey( const QString &key )
  95.     {
  96.       mKey = key;
  97.     }
  98.     
  99.     /**
  100.      * Return config file key.
  101.      */
  102.     QString key() const
  103.     {
  104.       return mKey;
  105.     }
  106.  
  107.     /**
  108.      * Set internal name of entry.
  109.      */
  110.     void setName(const QString &name)
  111.     {
  112.       mName = name;
  113.     }
  114.  
  115.     /**
  116.      * Return internal name of entry.
  117.      */
  118.     QString name() const
  119.     {
  120.       return mName;
  121.     }
  122.  
  123.     /**
  124.       Set label providing a translated one-line description of the item.
  125.     */
  126.     void setLabel( const QString &l )
  127.     {
  128.       mLabel = l;
  129.     }
  130.     
  131.     /**
  132.       Return label of item. See setLabel().
  133.     */
  134.     QString label() const
  135.     {
  136.       return mLabel;
  137.     }
  138.  
  139.     /**
  140.       Set WhatsThis description og item.
  141.     */
  142.     void setWhatsThis( const QString &w )
  143.     {
  144.       mWhatsThis = w;
  145.     }
  146.     
  147.     /**
  148.       Return WhatsThis description of item. See setWhatsThis().
  149.     */
  150.     QString whatsThis() const
  151.     {
  152.       return mWhatsThis;
  153.     }
  154.  
  155.     /**
  156.      * This function is called by @ref KConfigSkeleton to read the value for this setting
  157.      * from a config file.
  158.      * value.
  159.      */
  160.     virtual void readConfig(KConfig *) = 0;
  161.  
  162.     /**
  163.      * This function is called by @ref KConfigSkeleton to write the value of this setting
  164.      * to a config file.
  165.      */
  166.     virtual void writeConfig(KConfig *) = 0;
  167.  
  168.     /**
  169.      * Read global default value.
  170.      */
  171.     virtual void readDefault(KConfig *) = 0;
  172.  
  173.     /**
  174.      * Set item to @p p
  175.      */
  176.     virtual void setProperty(const QVariant &p) = 0;
  177.     
  178.     /**
  179.      * Return item as property
  180.      */
  181.     virtual QVariant property() const = 0;
  182.  
  183.     /**
  184.      * Return minimum value of item or invalid if not specified
  185.      */
  186.     virtual QVariant minValue() const { return QVariant(); }
  187.  
  188.     /**
  189.      * Return maximum value of item or invalid if not specified
  190.      */
  191.     virtual QVariant maxValue() const { return QVariant(); }
  192.  
  193.     /**
  194.       Sets the current value to the default value.
  195.     */
  196.     virtual void setDefault() = 0;
  197.  
  198.     /**
  199.      * Exchanges the current value with the default value
  200.      * Used by KConfigSkeleton::useDefaults(bool);
  201.      */
  202.     virtual void swapDefault() = 0;
  203.  
  204.     /**
  205.      * Return if the entry can be modified.
  206.      */
  207.     bool isImmutable() const
  208.     {
  209.       return mIsImmutable;
  210.     }
  211.  
  212.   protected:
  213.     /**
  214.      * sets mIsImmutable to true if mKey in config is immutable
  215.      * @param config KConfig to check if mKey is immutable in
  216.      */
  217.     void readImmutability(KConfig *config);
  218.  
  219.     QString mGroup;
  220.     QString mKey;
  221.     QString mName;
  222.  
  223.   private:
  224.     bool mIsImmutable;
  225.  
  226.     QString mLabel;
  227.     QString mWhatsThis;
  228.   };
  229.  
  230.  
  231. template < typename T > class KConfigSkeletonGenericItem:public KConfigSkeletonItem
  232.   {
  233.   public:
  234.     KConfigSkeletonGenericItem(const QString & group, const QString & key, T & reference,
  235.                 T defaultValue)
  236.       : KConfigSkeletonItem(group, key), mReference(reference),
  237.         mDefault(defaultValue), mLoadedValue(defaultValue)
  238.     {
  239.     }
  240.  
  241.     /**
  242.      * Set value of this KConfigSkeletonItem.
  243.      */
  244.     void setValue(const T & v)
  245.     {
  246.       mReference = v;
  247.     }
  248.  
  249.     /**
  250.      * Return value of this KConfigSkeletonItem.
  251.      */
  252.     T & value()
  253.     {
  254.       return mReference;
  255.     }
  256.  
  257.     /**
  258.      * Return const value of this KConfigSkeletonItem.
  259.      */
  260.     const T & value() const
  261.     {
  262.       return mReference;
  263.     }
  264.  
  265.     /**
  266.       Set default value for this item.
  267.     */
  268.     virtual void setDefaultValue( const T &v )
  269.     {
  270.       mDefault = v;
  271.     }
  272.  
  273.     virtual void setDefault()
  274.     {
  275.       mReference = mDefault;
  276.     }
  277.  
  278.     virtual void writeConfig(KConfig * config)
  279.     {
  280.       if ( mReference != mLoadedValue ) // Is this needed?
  281.       {
  282.         config->setGroup(mGroup);
  283.         if ((mDefault == mReference) && !config->hasDefault( mKey))
  284.           config->revertToDefault( mKey );
  285.         else
  286.           config->writeEntry(mKey, mReference);
  287.       }
  288.     }
  289.  
  290.     void readDefault(KConfig * config)
  291.     {
  292.       config->setReadDefaults(true);
  293.       readConfig(config);
  294.       config->setReadDefaults(false);
  295.       mDefault = mReference;
  296.     }
  297.  
  298.     void swapDefault()
  299.     {
  300.       T tmp = mReference;
  301.       mReference = mDefault;
  302.       mDefault = tmp;
  303.     }
  304.  
  305.   protected:
  306.     T & mReference;
  307.     T mDefault;
  308.     T mLoadedValue;
  309.   };
  310.  
  311.   /**
  312.    * @short Class for handling preferences settings for an application.
  313.    * @author Cornelius Schumacher
  314.    * @see KConfigSkeletonItem
  315.    * 
  316.    * This class provides an interface to preferences settings. Preferences items
  317.    * can be registered by the addItem() function corresponding to the data type of
  318.    * the seetting. KConfigSkeleton then handles reading and writing of config files and
  319.    * setting of default values.
  320.    * 
  321.    * Normally you will subclass KConfigSkeleton, add data members for the preferences
  322.    * settings and register the members in the constructor of the subclass.
  323.    * 
  324.    * Example:
  325.    * \code
  326.    * class MyPrefs : public KConfigSkeleton
  327.    * {
  328.    *   public:
  329.    *     MyPrefs()
  330.    *     {
  331.    *       setCurrentGroup("MyGroup");
  332.    *       addItemBool("MySetting1",mMyBool,false);
  333.    *       addItemColor("MySetting2",mMyColor,QColor(1,2,3));
  334.    * 
  335.    *       setCurrentGroup("MyOtherGroup");
  336.    *       addItemFont("MySetting3",mMyFont,QFont("helvetica",12));
  337.    *     }
  338.    * 
  339.    *     bool mMyBool;
  340.    *     QColor mMyColor;
  341.    *     QFont mMyFont;
  342.    * }
  343.    * \endcode
  344.    * 
  345.    * It might be convenient in many cases to make this subclass of KConfigSkeleton a
  346.    * singleton for global access from all over the application without passing
  347.    * references to the KConfigSkeleton object around.
  348.    * 
  349.    * You can write the data to the configuration file by calling @ref writeConfig()
  350.    * and read the data from the configuration file by calling @ref readConfig().
  351.    * 
  352.    * If you have items, which are not covered by the existing addItem() functions
  353.    * you can add customized code for reading, writing and default setting by
  354.    * implementing the functions @ref usrUseDefaults(), @ref usrReadConfig() and
  355.    * @ref usrWriteConfig().
  356.    * 
  357.    * Internally preferences settings are stored in instances of subclasses of
  358.    * @ref KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses 
  359.    * for your own types and call the generic @ref addItem() to register them.
  360.    *
  361.    * In many cases you don't have to write the specific KConfigSkeleton
  362.    * subclasses yourself, but you can use \ref kconfig_compiler to automatically
  363.    * generate the C++ code from an XML description of the configuration options.
  364.    */
  365. class KDECORE_EXPORT KConfigSkeleton
  366. {
  367. public:
  368.  
  369.   /**
  370.    * Class for handling a string preferences item.
  371.    */
  372.   class KDECORE_EXPORT ItemString:public KConfigSkeletonGenericItem < QString >
  373.   {
  374.   public:
  375.     enum Type { Normal, Password, Path };
  376.  
  377.     ItemString(const QString & group, const QString & key,
  378.                QString & reference,
  379.                const QString & defaultValue = QString::fromLatin1(""), // NOT QString::null !!
  380.                Type type = Normal);
  381.  
  382.     void writeConfig(KConfig * config);
  383.     void readConfig(KConfig * config);
  384.     void setProperty(const QVariant & p);
  385.     QVariant property() const;
  386.  
  387.   private:
  388.     Type mType;
  389.   };
  390.  
  391.   /**
  392.    * Class for handling a password preferences item.
  393.    */
  394.   class KDECORE_EXPORT ItemPassword:public ItemString
  395.   {
  396.   public:
  397.     ItemPassword(const QString & group, const QString & key,
  398.                QString & reference,
  399.                const QString & defaultValue = QString::fromLatin1("")); // NOT QString::null !!
  400.   };
  401.  
  402.   /**
  403.    * Class for handling a path preferences item.
  404.    */
  405.   class KDECORE_EXPORT ItemPath:public ItemString
  406.   {
  407.   public:
  408.     ItemPath(const QString & group, const QString & key,
  409.              QString & reference,
  410.              const QString & defaultValue = QString::null);
  411.   };
  412.  
  413.  
  414.   /**
  415.    * Class for handling a QVariant preferences item.
  416.    */
  417.   class KDECORE_EXPORT ItemProperty:public KConfigSkeletonGenericItem < QVariant >
  418.   {
  419.   public:
  420.     ItemProperty(const QString & group, const QString & key,
  421.                  QVariant & reference, QVariant defaultValue = 0);
  422.  
  423.     void readConfig(KConfig * config);
  424.     void setProperty(const QVariant & p);
  425.     QVariant property() const;
  426.   };
  427.  
  428.  
  429.   /**
  430.    * Class for handling a bool preferences item.
  431.    */
  432.   class KDECORE_EXPORT ItemBool:public KConfigSkeletonGenericItem < bool >
  433.   {
  434.   public:
  435.     ItemBool(const QString & group, const QString & key, bool & reference,
  436.              bool defaultValue = true);
  437.  
  438.     void readConfig(KConfig * config);
  439.     void setProperty(const QVariant & p);
  440.     QVariant property() const;
  441.   };
  442.  
  443.  
  444.   /**
  445.    * Class for handling an integer preferences item.
  446.    */
  447.   class KDECORE_EXPORT ItemInt:public KConfigSkeletonGenericItem < int >
  448.   {
  449.   public:
  450.     ItemInt(const QString & group, const QString & key, int &reference,
  451.             int defaultValue = 0);
  452.  
  453.     void readConfig(KConfig * config);
  454.     void setProperty(const QVariant & p);
  455.     QVariant property() const;
  456.     QVariant minValue() const;
  457.     QVariant maxValue() const;
  458.  
  459.     void setMinValue(int);
  460.     void setMaxValue(int);
  461.     
  462.   private:  
  463.     bool mHasMin : 1;
  464.     bool mHasMax : 1;
  465.     int mMin;
  466.     int mMax;
  467.   };
  468.  
  469.   /**
  470.    * Class for handling an 64-bit integer preferences item.
  471.    */
  472.   class KDECORE_EXPORT ItemInt64:public KConfigSkeletonGenericItem < Q_INT64 >
  473.   {
  474.   public:
  475.     ItemInt64(const QString & group, const QString & key, Q_INT64 &reference,
  476.             Q_INT64 defaultValue = 0);
  477.  
  478.     void readConfig(KConfig * config);
  479.     void setProperty(const QVariant & p);
  480.     QVariant property() const;
  481.  
  482.     QVariant minValue() const;
  483.     QVariant maxValue() const;
  484.  
  485.     void setMinValue(Q_INT64);
  486.     void setMaxValue(Q_INT64);
  487.     
  488.   private:  
  489.     bool mHasMin : 1;
  490.     bool mHasMax : 1;
  491.     Q_INT64 mMin;
  492.     Q_INT64 mMax;
  493.   };
  494.  
  495.   /**
  496.    * Class for handling enums.
  497.    */
  498.   class KDECORE_EXPORT ItemEnum:public ItemInt
  499.   {
  500.   public:
  501.     struct Choice
  502.     {
  503.       QString name;
  504.       QString label;
  505.       QString whatsThis;
  506.     };
  507.  
  508.     ItemEnum(const QString & group, const QString & key, int &reference,
  509.              const QValueList<Choice> &choices, int defaultValue = 0);
  510.  
  511.     QValueList<Choice> choices() const;
  512.  
  513.     void readConfig(KConfig * config);
  514.     void writeConfig(KConfig * config);
  515.  
  516.   private:
  517.       QValueList<Choice> mChoices;
  518.   };
  519.  
  520.  
  521.   /**
  522.    * Class for handling an unsingend integer preferences item.
  523.    */
  524.   class KDECORE_EXPORT ItemUInt:public KConfigSkeletonGenericItem < unsigned int >
  525.   {
  526.   public:
  527.     ItemUInt(const QString & group, const QString & key,
  528.              unsigned int &reference, unsigned int defaultValue = 0);
  529.  
  530.     void readConfig(KConfig * config);
  531.     void setProperty(const QVariant & p);
  532.     QVariant property() const;
  533.     QVariant minValue() const;
  534.     QVariant maxValue() const;
  535.  
  536.     void setMinValue(unsigned int);
  537.     void setMaxValue(unsigned int);
  538.     
  539.   private:  
  540.     bool mHasMin : 1;
  541.     bool mHasMax : 1;
  542.     unsigned int mMin;
  543.     unsigned int mMax;
  544.   };
  545.  
  546.  
  547.   /**
  548.    * Class for hanlding a long integer preferences item.
  549.    */
  550.   class KDECORE_EXPORT ItemLong:public KConfigSkeletonGenericItem < long >
  551.   {
  552.   public:
  553.     ItemLong(const QString & group, const QString & key, long &reference,
  554.              long defaultValue = 0);
  555.  
  556.     void readConfig(KConfig * config);
  557.     void setProperty(const QVariant & p);
  558.     QVariant property() const;
  559.     QVariant minValue() const;
  560.     QVariant maxValue() const;
  561.  
  562.     void setMinValue(long);
  563.     void setMaxValue(long);
  564.     
  565.   private:  
  566.     bool mHasMin : 1;
  567.     bool mHasMax : 1;
  568.     long mMin;
  569.     long mMax;
  570.   };
  571.  
  572.  
  573.   /**
  574.    * Class for handling an unsigned long integer preferences item.
  575.    */
  576.   class KDECORE_EXPORT ItemULong:public KConfigSkeletonGenericItem < unsigned long >
  577.   {
  578.   public:
  579.     ItemULong(const QString & group, const QString & key,
  580.               unsigned long &reference, unsigned long defaultValue = 0);
  581.  
  582.     void readConfig(KConfig * config);
  583.     void setProperty(const QVariant & p);
  584.     QVariant property() const;
  585.     QVariant minValue() const;
  586.     QVariant maxValue() const;
  587.  
  588.     void setMinValue(unsigned long);
  589.     void setMaxValue(unsigned long);
  590.     
  591.   private:  
  592.     bool mHasMin : 1;
  593.     bool mHasMax : 1;
  594.     unsigned long mMin;
  595.     unsigned long mMax;
  596.   };
  597.  
  598.   /**
  599.    * Class for handling unsigned 64-bit integer preferences item.
  600.    */
  601.   class KDECORE_EXPORT ItemUInt64:public KConfigSkeletonGenericItem < Q_UINT64 >
  602.   {
  603.   public:
  604.     ItemUInt64(const QString & group, const QString & key, Q_UINT64 &reference,
  605.             Q_UINT64 defaultValue = 0);
  606.  
  607.     void readConfig(KConfig * config);
  608.     void setProperty(const QVariant & p);
  609.     QVariant property() const;
  610.  
  611.     QVariant minValue() const;
  612.     QVariant maxValue() const;
  613.  
  614.     void setMinValue(Q_UINT64);
  615.     void setMaxValue(Q_UINT64);
  616.     
  617.   private:  
  618.     bool mHasMin : 1;
  619.     bool mHasMax : 1;
  620.     Q_UINT64 mMin;
  621.     Q_UINT64 mMax;
  622.   };
  623.  
  624.   /**
  625.    * Class for handling a floating point preference item.
  626.    */
  627.   class KDECORE_EXPORT ItemDouble:public KConfigSkeletonGenericItem < double >
  628.   {
  629.   public:
  630.     ItemDouble(const QString & group, const QString & key,
  631.                double &reference, double defaultValue = 0);
  632.  
  633.     void readConfig(KConfig * config);
  634.     void setProperty(const QVariant & p);
  635.     QVariant property() const;
  636.     QVariant minValue() const;
  637.     QVariant maxValue() const;
  638.  
  639.     void setMinValue(double);
  640.     void setMaxValue(double);
  641.     
  642.   private:  
  643.     bool mHasMin : 1;
  644.     bool mHasMax : 1;
  645.     double mMin;
  646.     double mMax;
  647.   };
  648.  
  649.  
  650.   /**
  651.    * Class for handling a color preferences item.
  652.    */
  653.   class KDECORE_EXPORT ItemColor:public KConfigSkeletonGenericItem < QColor >
  654.   {
  655.   public:
  656.     ItemColor(const QString & group, const QString & key,
  657.               QColor & reference,
  658.               const QColor & defaultValue = QColor(128, 128, 128));
  659.  
  660.     void readConfig(KConfig * config);
  661.     void setProperty(const QVariant & p);
  662.     QVariant property() const;
  663.   };
  664.  
  665.  
  666.   /**
  667.    * Class for handling a font preferences item.
  668.    */
  669.   class KDECORE_EXPORT ItemFont:public KConfigSkeletonGenericItem < QFont >
  670.   {
  671.   public:
  672.     ItemFont(const QString & group, const QString & key, QFont & reference,
  673.              const QFont & defaultValue = KGlobalSettings::generalFont());
  674.  
  675.     void readConfig(KConfig * config);
  676.     void setProperty(const QVariant & p);
  677.     QVariant property() const;
  678.   };
  679.  
  680.  
  681.   /**
  682.    * Class for handling a QRect preferences item.
  683.    */
  684.   class KDECORE_EXPORT ItemRect:public KConfigSkeletonGenericItem < QRect >
  685.   {
  686.   public:
  687.     ItemRect(const QString & group, const QString & key, QRect & reference,
  688.              const QRect & defaultValue = QRect());
  689.  
  690.     void readConfig(KConfig * config);
  691.     void setProperty(const QVariant & p);
  692.     QVariant property() const;
  693.   };
  694.  
  695.  
  696.   /**
  697.    * Class for handling a QPoint preferences item.
  698.    */
  699.   class KDECORE_EXPORT ItemPoint:public KConfigSkeletonGenericItem < QPoint >
  700.   {
  701.   public:
  702.     ItemPoint(const QString & group, const QString & key, QPoint & reference,
  703.               const QPoint & defaultValue = QPoint());
  704.  
  705.     void readConfig(KConfig * config);
  706.     void setProperty(const QVariant & p);
  707.     QVariant property() const;
  708.   };
  709.  
  710.  
  711.   /**
  712.    * Class for handling a QSize preferences item.
  713.    */
  714.   class KDECORE_EXPORT ItemSize:public KConfigSkeletonGenericItem < QSize >
  715.   {
  716.   public:
  717.     ItemSize(const QString & group, const QString & key, QSize & reference,
  718.              const QSize & defaultValue = QSize());
  719.  
  720.     void readConfig(KConfig * config);
  721.     void setProperty(const QVariant & p);
  722.     QVariant property() const;
  723.   };
  724.  
  725.  
  726.   /**
  727.    * Class for handling a QDateTime preferences item.
  728.    */
  729.   class KDECORE_EXPORT ItemDateTime:public KConfigSkeletonGenericItem < QDateTime >
  730.   {
  731.   public:
  732.     ItemDateTime(const QString & group, const QString & key,
  733.                  QDateTime & reference,
  734.                  const QDateTime & defaultValue = QDateTime());
  735.  
  736.     void readConfig(KConfig * config);
  737.     void setProperty(const QVariant & p);
  738.     QVariant property() const;
  739.   };
  740.  
  741.  
  742.   /**
  743.    * Class for handling a string list preferences item.
  744.    */
  745.   class KDECORE_EXPORT ItemStringList:public KConfigSkeletonGenericItem < QStringList >
  746.   {
  747.   public:
  748.     ItemStringList(const QString & group, const QString & key,
  749.                    QStringList & reference,
  750.                    const QStringList & defaultValue = QStringList());
  751.  
  752.     void readConfig(KConfig * config);
  753.     void setProperty(const QVariant & p);
  754.     QVariant property() const;
  755.   };
  756.  
  757.  
  758.   /**
  759.    * Class for handling a path list preferences item.
  760.    */
  761.   class KDECORE_EXPORT ItemPathList:public ItemStringList
  762.   {
  763.   public:
  764.     ItemPathList(const QString & group, const QString & key,
  765.                    QStringList & reference,
  766.                    const QStringList & defaultValue = QStringList());
  767.  
  768.     void readConfig(KConfig * config);
  769.     void writeConfig(KConfig * config);
  770.   };
  771.  
  772.  
  773.   /**
  774.    * Class for handling an integer list preferences item.
  775.    */
  776.   class KDECORE_EXPORT ItemIntList:public KConfigSkeletonGenericItem < QValueList < int > >
  777.   {
  778.   public:
  779.     ItemIntList(const QString & group, const QString & key,
  780.                 QValueList < int >&reference,
  781.                 const QValueList < int >&defaultValue = QValueList < int >());
  782.  
  783.     void readConfig(KConfig * config);
  784.     void setProperty(const QVariant & p);
  785.     QVariant property() const;
  786.   };
  787.  
  788.  
  789. public:
  790.   /**
  791.    * Constructor.
  792.    * 
  793.    * @param configname name of config file. If no name is given, the default
  794.    * config file as returned by kapp()->config() is used.
  795.    */
  796.   KConfigSkeleton(const QString & configname = QString::null);
  797.  
  798.   /**
  799.    * Constructor.
  800.    * 
  801.    * @param config configuration object to use.
  802.    */
  803.   KConfigSkeleton(KSharedConfig::Ptr config);
  804.  
  805.   /**
  806.    * Destructor
  807.    */
  808.     virtual ~ KConfigSkeleton();
  809.  
  810.   /**
  811.     Set all registered items to their default values.
  812.   */
  813.   void setDefaults();
  814.  
  815.   /**
  816.    * Read preferences from config file. All registered items are set to the
  817.    * values read from disk.
  818.    */
  819.   void readConfig();
  820.  
  821.   /**
  822.    * Write preferences to config file. The values of all registered items are
  823.    * written to disk.
  824.    */
  825.   void writeConfig();
  826.  
  827.   /**
  828.    * Set the config file group for subsequent addItem() calls. It is valid
  829.    * until setCurrentGroup() is called with a new argument. Call this before
  830.    * you add any items. The default value is "No Group".
  831.    */
  832.   void setCurrentGroup(const QString & group);
  833.  
  834.   /**
  835.    * Returns the current group used for addItem() calls. 
  836.    */
  837.   QString currentGroup() // ### KDE 4.0: make const
  838.   {
  839.     return mCurrentGroup;
  840.   }
  841.  
  842.   /**
  843.    * Register a custom @ref KConfigSkeletonItem with a given name. If the name
  844.    * parameter is null, take the name from KConfigSkeletonItem::key().
  845.    * Note that all names must be unique but that multiple entries can have
  846.    * the same key if they reside in different groups. 
  847.    */
  848.   void addItem(KConfigSkeletonItem *, const QString & name = QString::null );
  849.  
  850.   /**
  851.    * Register an item of type QString.
  852.    * 
  853.    * @param name Name used to indentify this setting. Names must be unique.
  854.    * @param reference Pointer to the variable, which is set by readConfig()
  855.    * calls and read by writeConfig() calls.
  856.    * @param defaultValue Default value, which is used when the config file 
  857.    * does not yet contain the key of this item.
  858.    * @param key Key used in config file. If key is null, name is used as key.
  859.    * @return The created item
  860.    */
  861.   ItemString *addItemString(const QString & name, QString & reference,
  862.                             const QString & defaultValue = QString::fromLatin1(""), // NOT QString::null !!
  863.                             const QString & key = QString::null);
  864.  
  865.   /**
  866.    * Register a password item of type QString. The string value is written 
  867.    * encrypted to the config file. Note that the current encryption scheme 
  868.    * is very weak.
  869.    * 
  870.    * @param name Name used to indentify this setting. Names must be unique.
  871.    * @param reference Pointer to the variable, which is set by readConfig()
  872.    * calls and read by writeConfig() calls.
  873.    * @param defaultValue Default value, which is used when the config file
  874.    * does not yet contain the key of this item.
  875.    * @param key Key used in config file. If key is null, name is used as key.
  876.    * @return The created item
  877.    */
  878.   ItemPassword *addItemPassword(const QString & name, QString & reference,
  879.                               const QString & defaultValue = QString::fromLatin1(""),
  880.                               const QString & key = QString::null);
  881.  
  882.   /**
  883.    * Register a path item of type QString. The string value is interpreted
  884.    * as a path. This means, dollar expension is activated for this value, so
  885.    * that e.g. $HOME gets expanded. 
  886.    * 
  887.    * @param name Name used to indentify this setting. Names must be unique.
  888.    * @param reference Pointer to the variable, which is set by readConfig()
  889.    * calls and read by writeConfig() calls.
  890.    * @param defaultValue Default value, which is used when the config file
  891.    * does not yet contain the key of this item.
  892.    * @param key Key used in config file. If key is null, name is used as key.
  893.    * @return The created item
  894.    */
  895.   ItemPath *addItemPath(const QString & name, QString & reference,
  896.                           const QString & defaultValue = QString::fromLatin1(""),
  897.                           const QString & key = QString::null);
  898.  
  899.   /**
  900.    * Register a property item of type QVariant. Note that only the following
  901.    * QVariant types are allowed: String, StringList, Font, Point, Rect, Size,
  902.    * Color, Int, UInt, Bool, Double, DateTime and Date.
  903.    * 
  904.    * @param name Name used to indentify this setting. Names must be unique.
  905.    * @param reference Pointer to the variable, which is set by readConfig()
  906.    * calls and read by writeConfig() calls.
  907.    * @param defaultValue Default value, which is used when the config file
  908.    * does not yet contain the key of this item.
  909.    * @param key Key used in config file. If key is null, name is used as key.
  910.    * @return The created item
  911.    */
  912.   ItemProperty *addItemProperty(const QString & name, QVariant & reference,
  913.                                 const QVariant & defaultValue = QVariant(),
  914.                                 const QString & key = QString::null);
  915.   /**
  916.    * Register an item of type bool.
  917.    * 
  918.    * @param name Name used to indentify this setting. Names must be unique.
  919.    * @param reference Pointer to the variable, which is set by readConfig()
  920.    * calls and read by writeConfig() calls.
  921.    * @param defaultValue Default value, which is used when the config file
  922.    * does not yet contain the key of this item.
  923.    * @param key Key used in config file. If key is null, name is used as key.
  924.    * @return The created item
  925.    */
  926.   ItemBool *addItemBool(const QString & name, bool & reference,
  927.                         bool defaultValue = false,
  928.                         const QString & key = QString::null);
  929.  
  930.   /**
  931.    * Register an item of type int.
  932.    * 
  933.    * @param name Name used to indentify this setting. Names must be unique.
  934.    * @param reference Pointer to the variable, which is set by readConfig()
  935.    * calls and read by writeConfig() calls.
  936.    * @param defaultValue Default value, which is used when the config file
  937.    * does not yet contain the key of this item.
  938.    * @param key Key used in config file. If key is null, name is used as key.
  939.    * @return The created item
  940.    */
  941.   ItemInt *addItemInt(const QString & name, int &reference, int defaultValue = 0,
  942.                       const QString & key = QString::null);
  943.  
  944.   /**
  945.    * Register an item of type unsigned int.
  946.    * 
  947.    * @param name Name used to indentify this setting. Names must be unique.
  948.    * @param reference Pointer to the variable, which is set by readConfig()
  949.    * calls and read by writeConfig() calls.
  950.    * @param defaultValue Default value, which is used when the config file
  951.    * does not yet contain the key of this item.
  952.    * @param key Key used in config file. If key is null, name is used as key.
  953.    * @return The created item
  954.    */
  955.   ItemUInt *addItemUInt(const QString & name, unsigned int &reference,
  956.                         unsigned int defaultValue = 0,
  957.                         const QString & key = QString::null);
  958.  
  959.   /**
  960.    * Register an item of type long.
  961.    * 
  962.    * @param name Name used to indentify this setting. Names must be unique.
  963.    * @param reference Pointer to the variable, which is set by readConfig()
  964.    * calls and read by writeConfig() calls.
  965.    * @param defaultValue Default value, which is used when the config file
  966.    * does not yet contain the key of this item.
  967.    * @param key Key used in config file. If key is null, name is used as key.
  968.    * @return The created item
  969.    */
  970.   ItemLong *addItemLong(const QString & name, long &reference,
  971.                         long defaultValue = 0,
  972.                         const QString & key = QString::null);
  973.  
  974.   /**
  975.    * Register an item of type unsigned long.
  976.    * 
  977.    * @param name Name used to indentify this setting. Names must be unique.
  978.    * @param reference Pointer to the variable, which is set by readConfig()
  979.    * calls and read by writeConfig() calls.
  980.    * @param defaultValue Default value, which is used when the config file
  981.    * does not yet contain the key of this item.
  982.    * @param key Key used in config file. If key is null, name is used as key.
  983.    * @return The created item
  984.    */
  985.   ItemULong *addItemULong(const QString & name, unsigned long &reference,
  986.                           unsigned long defaultValue = 0,
  987.                           const QString & key = QString::null);
  988.  
  989.   /**
  990.    * Register an item of type Q_INT64.
  991.    * 
  992.    * @param name Name used to indentify this setting. Names must be unique.
  993.    * @param reference Pointer to the variable, which is set by readConfig()
  994.    * calls and read by writeConfig() calls.
  995.    * @param defaultValue Default value, which is used when the config file
  996.    * does not yet contain the key of this item.
  997.    * @param key Key used in config file. If key is null, name is used as key.
  998.    * @return The created item
  999.    */
  1000.   ItemInt64 *addItemInt64(const QString & name, Q_INT64 &reference,
  1001.                           Q_INT64 defaultValue = 0,
  1002.                           const QString & key = QString::null);
  1003.  
  1004.   /**
  1005.    * Register an item of type Q_UINT64
  1006.    * 
  1007.    * @param name Name used to indentify this setting. Names must be unique.
  1008.    * @param reference Pointer to the variable, which is set by readConfig()
  1009.    * calls and read by writeConfig() calls.
  1010.    * @param defaultValue Default value, which is used when the config file
  1011.    * does not yet contain the key of this item.
  1012.    * @param key Key used in config file. If key is null, name is used as key.
  1013.    * @return The created item
  1014.    */
  1015.   ItemUInt64 *addItemUInt64(const QString & name, Q_UINT64 &reference,
  1016.                             Q_UINT64 defaultValue = 0,
  1017.                             const QString & key = QString::null);
  1018.  
  1019.   /**
  1020.    * Register an item of type double.
  1021.    * 
  1022.    * @param name Name used to indentify this setting. Names must be unique.
  1023.    * @param reference Pointer to the variable, which is set by readConfig()
  1024.    * calls and read by writeConfig() calls.
  1025.    * @param defaultValue Default value, which is used when the config file
  1026.    * does not yet contain the key of this item.
  1027.    * @param key Key used in config file. If key is null, name is used as key.
  1028.    * @return The created item
  1029.    */
  1030.   ItemDouble *addItemDouble(const QString & name, double &reference,
  1031.                             double defaultValue = 0.0,
  1032.                             const QString & key = QString::null);
  1033.  
  1034.   /**
  1035.    * Register an item of type QColor.
  1036.    * 
  1037.    * @param name Name used to indentify this setting. Names must be unique.
  1038.    * @param reference Pointer to the variable, which is set by readConfig()
  1039.    * calls and read by writeConfig() calls.
  1040.    * @param defaultValue Default value, which is used when the config file
  1041.    * does not yet contain the key of this item.
  1042.    * @param key Key used in config file. If key is null, name is used as key.
  1043.    * @return The created item
  1044.    */
  1045.   ItemColor *addItemColor(const QString & name, QColor & reference,
  1046.                           const QColor & defaultValue = QColor(128, 128, 128),
  1047.                           const QString & key = QString::null);
  1048.  
  1049.   /**
  1050.    * Register an item of type QFont.
  1051.    * 
  1052.    * @param name Name used to indentify this setting. Names must be unique.
  1053.    * @param reference Pointer to the variable, which is set by readConfig()
  1054.    * calls and read by writeConfig() calls.
  1055.    * @param defaultValue Default value, which is used when the config file
  1056.    * does not yet contain the key of this item.
  1057.    * @param key Key used in config file. If key is null, name is used as key.
  1058.    * @return The created item
  1059.    */
  1060.   ItemFont *addItemFont(const QString & name, QFont & reference,
  1061.                         const QFont & defaultValue =
  1062.                         KGlobalSettings::generalFont(),
  1063.                         const QString & key = QString::null);
  1064.  
  1065.   /**
  1066.    * Register an item of type QRect.
  1067.    * 
  1068.    * @param name Name used to indentify this setting. Names must be unique.
  1069.    * @param reference Pointer to the variable, which is set by readConfig()
  1070.    * calls and read by writeConfig() calls.
  1071.    * @param defaultValue Default value, which is used when the config file
  1072.    * does not yet contain the key of this item.
  1073.    * @param key Key used in config file. If key is null, name is used as key.
  1074.    * @return The created item
  1075.    */
  1076.   ItemRect *addItemRect(const QString & name, QRect & reference,
  1077.                         const QRect & defaultValue = QRect(),
  1078.                         const QString & key = QString::null);
  1079.  
  1080.   /**
  1081.    * Register an item of type QPoint.
  1082.    * 
  1083.    * @param name Name used to indentify this setting. Names must be unique.
  1084.    * @param reference Pointer to the variable, which is set by readConfig()
  1085.    * calls and read by writeConfig() calls.
  1086.    * @param defaultValue Default value, which is used when the config file
  1087.    * does not yet contain the key of this item.
  1088.    * @param key Key used in config file. If key is null, name is used as key.
  1089.    * @return The created item
  1090.    */
  1091.   ItemPoint *addItemPoint(const QString & name, QPoint & reference,
  1092.                           const QPoint & defaultValue = QPoint(),
  1093.                           const QString & key = QString::null);
  1094.  
  1095.   /**
  1096.    * Register an item of type QSize.
  1097.    * 
  1098.    * @param name Name used to indentify this setting. Names must be unique.
  1099.    * @param reference Pointer to the variable, which is set by readConfig()
  1100.    * calls and read by writeConfig() calls.
  1101.    * @param defaultValue Default value, which is used when the config file
  1102.    * does not yet contain the key of this item.
  1103.    * @param key Key used in config file. If key is null, name is used as key.
  1104.    * @return The created item
  1105.    */
  1106.   ItemSize *addItemSize(const QString & name, QSize & reference,
  1107.                         const QSize & defaultValue = QSize(),
  1108.                         const QString & key = QString::null);
  1109.  
  1110.   /**
  1111.    * Register an item of type QDateTime.
  1112.    * 
  1113.    * @param name Name used to indentify this setting. Names must be unique.
  1114.    * @param reference Pointer to the variable, which is set by readConfig()
  1115.    * calls and read by writeConfig() calls.
  1116.    * @param defaultValue Default value, which is used when the config file
  1117.    * does not yet contain the key of this item.
  1118.    * @param key Key used in config file. If key is null, name is used as key.
  1119.    * @return The created item
  1120.    */
  1121.   ItemDateTime *addItemDateTime(const QString & name, QDateTime & reference,
  1122.                                 const QDateTime & defaultValue = QDateTime(),
  1123.                                 const QString & key = QString::null);
  1124.  
  1125.   /**
  1126.    * Register an item of type QStringList.
  1127.    * 
  1128.    * @param name Name used to indentify this setting. Names must be unique.
  1129.    * @param reference Pointer to the variable, which is set by readConfig()
  1130.    * calls and read by writeConfig() calls.
  1131.    * @param defaultValue Default value, which is used when the config file
  1132.    * does not yet contain the key of this item.
  1133.    * @param key Key used in config file. If key is null, name is used as key.
  1134.    * @return The created item
  1135.    */
  1136.   ItemStringList *addItemStringList(const QString & name, QStringList & reference,
  1137.                                     const QStringList & defaultValue = QStringList(),
  1138.                                     const QString & key = QString::null);
  1139.  
  1140.   /**
  1141.    * Register an item of type QValueList<int>.
  1142.    * 
  1143.    * @param name Name used to indentify this setting. Names must be unique.
  1144.    * @param reference Pointer to the variable, which is set by readConfig()
  1145.    * calls and read by writeConfig() calls.
  1146.    * @param defaultValue Default value, which is used when the config file
  1147.    * does not yet contain the key of this item.
  1148.    * @param key Key used in config file. If key is null, name is used as key.
  1149.    * @return The created item
  1150.    */
  1151.   ItemIntList *addItemIntList(const QString & name, QValueList < int >&reference,
  1152.                               const QValueList < int >&defaultValue =
  1153.                               QValueList < int >(),
  1154.                               const QString & key = QString::null);
  1155.  
  1156.   /**
  1157.    * Return the @ref KConfig object used for reading and writing the settings.
  1158.    */
  1159.   KConfig *config() const;
  1160.  
  1161.   /**
  1162.    * Return list of items managed by this KConfigSkeleton object.
  1163.    */
  1164.   KConfigSkeletonItem::List items() const
  1165.   {
  1166.     return mItems;
  1167.   }
  1168.  
  1169.   /**
  1170.    * Return whether a certain item is immutable
  1171.    */
  1172.   bool isImmutable(const QString & name);
  1173.  
  1174.   /**
  1175.    * Lookup item by name
  1176.    */
  1177.   KConfigSkeletonItem * findItem(const QString & name);
  1178.  
  1179.   /**
  1180.    * Indicate whether this object should reflect the actual
  1181.    * values or the default values.
  1182.    * @param b If true this object reflects the default values.
  1183.    * @return The state prior to this call
  1184.    */
  1185.   bool useDefaults(bool b);
  1186.  
  1187. protected:
  1188.   /**
  1189.    * Implemented by subclasses that use special defaults.
  1190.    * It should replace the default values with the actual
  1191.    * values and vice versa.
  1192.    */
  1193.   virtual void usrUseDefaults(bool)
  1194.   {
  1195.   }
  1196.  
  1197.   virtual void usrSetDefaults()
  1198.   {
  1199.   }
  1200.  
  1201.   /**
  1202.    * Implemented by subclasses that read special config values.
  1203.    */
  1204.   virtual void usrReadConfig()
  1205.   {
  1206.   }
  1207.  
  1208.   /**
  1209.    * Implemented by subclasses that write special config values.
  1210.    */
  1211.   virtual void usrWriteConfig()
  1212.   {
  1213.   }
  1214.  
  1215. private:
  1216.   QString mCurrentGroup;
  1217.  
  1218.   KSharedConfig::Ptr mConfig; // pointer to KConfig object
  1219.  
  1220.   KConfigSkeletonItem::List mItems;
  1221.   KConfigSkeletonItem::Dict mItemDict;
  1222.   
  1223.   bool mUseDefaults;
  1224.  
  1225.   class Private;
  1226.   Private *d;
  1227.  
  1228. };
  1229.  
  1230. #endif
  1231.